package com.googlecode.simplexer;

import com.googlecode.simplexer.exception.ParseException;
import com.googlecode.simplexer.validator.Validator;

/**
 * Lexer interface.
 * 
 * @author Sam Huang
 */
public interface Lexer {

	/**
	 * Move the pointer back $length characters long.
	 * 
	 * @param length
	 *            length to move backward
	 */
	public void backward(int length);

	/**
	 * Move the pointer back.
	 * 
	 * @param token
	 */
	public void backward(String token);

	/**
	 * Sends an error message.
	 * 
	 * @param errorMessage
	 * @throws ParseException
	 */
	public void error(String errorMessage) throws ParseException;

	/**
	 * Forward
	 * @param length
	 * @return
	 */
	public String forward(int length);

	/**
	 * Forward with the length of the given token.
	 * 
	 * @param token the token to be skipped
	 * @return the skipped content
	 */
	public String forward(String token);

	/**
	 * Forward until the given character is reached.
	 * 
	 * @param chr the character to be found
	 * @return the skipped content
	 */
	public String forwardUntil(char chr);

	/**
	 * Forward until the given token is reached.
	 * 
	 * @param token the token to be found
	 * @return the skipped content
	 */
	public String forwardUntil(String token);

	/**
	 * Forward until the token meets the criteria of the given validator.
	 * 
	 * @param v the validator
	 * @return the skipped content
	 */
	public String forwardUntil(Validator v);

	/**
	 * Return the current column.
	 * 
	 * @return the current col
	 */
	public int getColumn();

	/**
	 * Return the line.
	 * 
	 * @return the current line
	 */
	public String getLine();

	/**
	 * Return the current line number.
	 * 
	 * @return the current line number
	 */
	public int getLineNumber();

	/**
	 * Return the source name.
	 * 
	 * @return the source name
	 */
	public String getSourceName();

	/**
	 * Return the next char.
	 * 
	 * @return the next char
	 */
	public char nextchar();

	/**
	 * Get the next char and check it against the expected one.
	 * 
	 * @param chr the expected char
	 * @return the next char
	 */
	public char nextchar(char chr);

	/**
	 * Return the next char.
	 * 
	 * @return the next char
	 * @throws Exception
	 */
	public char nextchr() throws Exception;

	/**
	 * Proceed to the next line.
	 * 
	 * @throws Exception
	 */
	public void nextLine() throws Exception;

	/**
	 * Return the next token.
	 * 
	 * @return the next token
	 * @throws Exception
	 */
	public String nexttk() throws Exception;

	/**
	 * Return the next token.
	 * 
	 * @return
	 * @throws UnsupportedOperationException
	 */
	public String nexttok() throws UnsupportedOperationException;

	/**
	 * Get the next token and check its length against to the expected length.
	 * 
	 * @param length the expected length
	 * @return
	 * @throws UnsupportedOperationException
	 */
	public String nexttok(int length) throws UnsupportedOperationException;

	/**
	 * Get the next token and check it against to the expected tokens.
	 * 
	 * @param tokens the expected tokens
	 * @return the next token
	 * @throws UnsupportedOperationException
	 */
	public String nexttok(String... tokens)
			throws UnsupportedOperationException;

	/**
	 * Get the next token and check it against to the expected token types.
	 * 
	 * @param verifiers the expected token types
	 * @return the next token
	 * @throws UnsupportedOperationException
	 */
	public String nexttok(Validator... verifiers)
			throws UnsupportedOperationException;

	/**
	 * Skip everything until the given char is reached.
	 * 
	 * @param chr
	 * @return the skipped stream
	 * @throws UnsupportedOperationException
	 * @deprecated Use {@link #skipTo(char)} instead
	 */
	public String skip(char chr) throws UnsupportedOperationException;

	/**
	 * Skip everything until the given char is reached.
	 * 
	 * @param chr
	 * @return the skipped stream
	 * @throws UnsupportedOperationException
	 */
	public String skipTo(char chr) throws UnsupportedOperationException;

	/**
	 * Skip everything inside quoted.
	 * 
	 * @return the skipped text
	 */
	public String skipQutedString();
}
